Telephony events

Note: Telephony events are delivered to the LLM as “fake” user utterances (see below). This works for all regular (non-speech-to-speech) models and for speech-to-speech models from OpenAI / Azure OpenAI, Google, xAI, and Amazon nova-2-sonic. The only exception is Amazon nova-sonic (v1), which reacts only to actual user speech and therefore ignores these events — use nova-2-sonic instead. See Speech-to-speech models.

Agents support handling of the following telephony events during voice conversations:

DTMF digits

When the user presses keypad digits during the call, the Bot connection associated with the AI Agent generates a DTMFDigits event. This may be used to create legacy IVR-like bots or to implement a shortcut for transfer to human agent.

To enable a DTMFDigits event, turn on the DTMF toggle in Settings tab in Bot connection’s configuration screen, or in Speech and Telephony tab in Agent’s configuration screen.

By default, the Bot connection sends each digit as a separate DTMFDigits event. To collect multiple digits and send them as a single DTMFDigits event, add the following to your Bot connection's Advanced configuration:

{
    "dtmfCollect": true,
    "dtmfCollectMaxDigits": 10
}

For additional collection options, see Voice AI Connect > Bot integration > Receiving notifications > DTMF digits.

AI Agents convert the DTMFDigits event into a “fake” DTMF-[digits] user utterance sent to the LLM, where [digits] are the collected digits.

Include explicit instructions in your prompt on how to react to DTMF-[digits] messages.

Example
If user says "DTMF-1" pass the call to helpdesk agent.
If user says "DTMF-2" pass the call to escalation agent.

Answering machine detection

When the Bot connection associated with the AI Agent detects an answering machine, it generates a MachineDetection event. This is primarily relevant for outbound calls and can be used to prevent the agent from wasting time and outbound calling credits.

To enable a MachineDetection event, add the following to your Bot connection's Advanced configuration.

{
    "machineDetection": "detect"
}

AI Agents convert the MachineDetection event into a “fake” VOICEMAIL-DETECTED user utterance sent to the LLM.

Include explicit instructions in your prompt on how to react to VOICEMAIL-DETECTED messages.

Example
Respond to "VOICEMAIL-DETECTED" with calling `end_call` tool and saying "Hi, this
is Adelle from City Hall. I just wanted to let you know that your application for
the pool renovation has been approved! Give me a call back when you get a chance,
and I'll go over the details with you. Thanks!"

To disconnect the call upon answering machine detection, set machineDetection property to disconnect. The disconnect will be handled by the Bot Connection, with no AI Agent / LLM involvement.

For more information, see Voice AI Connect > Bot integration > Outbound calling.

Testing in Chat

Because these events are delivered as “fake” user utterances, you can test how your agent reacts to them directly in Chat — simply type the utterance (for example, DTMF-1 or VOICEMAIL-DETECTED) and inspect your agent’s response.